/*
 *  Copyright 2008 Mark Ashworth <javameme@gmail.com>.
 * 
 *  Licensed under the GNU General Public License v3 (the "License");
 *  you may not use this file except in compliance with the License.
 *  You may obtain a copy of the License at
 * 
 *       http://www.gnu.org/licenses/gpl-3.0.html
 * 
 *  Unless required by applicable law or agreed to in writing, software
 *  distributed under the License is distributed on an "AS IS" BASIS,
 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *  See the License for the specific language governing permissions and
 *  limitations under the License.
 *  under the License.
 */
package metaphor.persistence.xml;

import org.dom4j.Element;

/**
 * The reference resolver resolves references in the XML document to persistent
 * class instances that might have been processed before. For example:<br /><br />
 * 
 * &lt;xperiment.metaphor.model.people.Gender name="MALE" /&gt;<br /><br />
 * &lt;xperiment.metaphor.model.people.Person first_name="Mark" &gt;<br />
 * &lt;xperiment.metaphor.model.people.Gender name="MALE" /&gt;<br />
 * &lt;/xperiment.metaphor.model.people.Person&gt;<br /><br />
 * 
 * In the above XML the gender would be persisted first and then when the 
 * person instance needed to be persisted the underlying persistence framework
 * would not be able to persist the gender reference or would attempt to duplicate
 * the entry in the database.<br />
 * 
 * @author Mark Ashworth <javameme@gmail.com>
 * @version 1.0.0
 */
public interface ReferenceResolver {
    /**
     * The persistent class resolver to use
     * @return PersistentClassResolver
     */
    PersistentClassResolver getClassResolver();
    
    /**
     * The class resolver
     * @param classResolver The new value
     */
    void setClassResolver(PersistentClassResolver classResolver);
    /**
     * Determines if the XML element is supported by this resolver
     * @param element The ement to determine if it is supported by the resolver
     * @return boolean
     */
    boolean supports(Element element);

    /**
     * Resolves the XML element to a persisted instance
     * @param element The XML element
     */
    void resolve(Element element);
}
